Account Events Lifecycle Guide
Important: Although this guide focuses on savings account events, the lifecycle information is applicable to other kinds of bank account too, including current accounts.
This guide describes a sample lifecycle for bank account events. It focuses on a saving account (without term), but the lifecycle information is applicable to other kinds of bank account too, including current accounts. We won't be able to explore everything that can happen in an account, but it should give you a good idea of the major events you can expect in such an account. For clarity, we're focusing on user initiated transactions. System managed activities, such as Capitalization of interest schedule are not shown.
Scenario
In this scenario, we're assuming that the origination/onboarding process which initiates account creation have already happened, and that an API is initiated to create the account.
We begin with creation, then move onto setting up an overdraft limit (this can be set at the product level too, and isn't mandatory, but could be amended at the account level). A credit occurs, and the lifecycle assumes the subsequent debt, which utilises - and can also age - the overdraft facility. The overdraft is never paid, and the account reaches dormancy, and is subsequently closed. We'll deal with each of these stages in detail in the sections below, and look at the event payloads.
Note: Dormancy can happen automatically as well, but in our example, it's actioned manually.
Lifecycle Diagram
To keep things simple, the lifecycle is shown as a straightforward, linear timeline.
Legend
|
|
The API URL that's used to carry out this business process. |
 |
API request (typically, a command to perform an operation). |
 |
The event type that's emanated. |
 |
Business event emanating after the process is completed by the system. |
 |
Business process in the system. |
 |
Completion of the business process in the system. |
Tip: Click diagram to expand.
Account Creation
API
The API that's used to create the savings account.
/v1.0.0/holdings/accounts/savingsAccounts/
Event
The event that's emanated at account creation.
accounts.createAccount.accountCreated
Event Payload
baseDetails |
Typically contains all the basic account information – such as the account reference, system name, transaction reference, and the effective date of the event - and is defaulted for all events. |
feeDetails |
Contains the fee that's incurred when performing this transaction. It's useful for passing details to pricing systems which can compute benefits on top of the fee. The object is populated only if a fee is incurred. |
accountsBaseDetails |
Carries the overdraft and dormancy statuses (TBCs can have multiple OD and Dormancy statuses, and are configurable).If the account is a multi-currency (MCY) account, it also carries the MCY details and their individual balances. Not populated if the account is a normal account. |
balances |
Contains an array of balances affected by the transaction. |
alternateReferences |
Carries the list of alternate references that have been recorded for this account as Type/ID pair. |
Note: All the subsequent objects carry the individual, salient property details of the account, such as the parties involved, the repayment schedule(capitalisation frequency), limits, renewal details, and so on.
- Sample Code: Account Creation Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "productName": "dddddddd", "originalContractDate": "ee", "baseDetails": [ { "contractReference": "DDDDDD", "systemReference": "CCCC", "companyReference": "BBBBB", "eventName": "", "baseEventIdentifier": "b", "effectiveDate": "ddddddddd", "bookingDate": "EEEE", "contractCurrency": "AAAAAA", "channel": "BBBBBBBB", "branch": "eeeeee", "lineOfBusiness": "CCCCCCCC", "activityDateTimeStamp": "ccccccccc", "transactionReference": "ddddd", "reversalIndicator": false, "originationReference": "", "contractStatus": "BBB", "accountId": "BBBBB", "overdue": "", "feeDetails": [ { "feeName": "DDDDDDD", "feeAmount": "", "feeCurrency": "bbbbb", "adjustFeeAmount": "aaaa", "adjustFeeReason": "" } ], "balances": [ { "balanceName": "cccccccc", "closingBalance": "A", "dateType": "A", "debitTotalAmount": "", "creditTotalAmount": "bbbbbbbb", "timeStamp": "dddd" } ] } ], "accountsBaseDetails": [ { "overdraftStatus": "DDDDDDDDD", "dormancyStatus": "", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "cccccccc", "currency": "ddd", "multiCurrencyAccountBalances": [ { "currency": "aaaaaaa", "balances": [ { "balanceName": "eeeeee", "closingBalance": "", "dateType": "EEEEEE", "debitTotalAmount": "DDDD", "creditTotalAmount": "eeeeeeeee", "timeStamp": "ccccc" } ] } ] } ] } ], "alternateReferences": [ { "alternateIdType": "eeeeeeeee", "alternateId": "CCCCC" } ], "party": [ { "partyReference": "eeeeeeeee", "partyRole": "bbbbbbbbb" } ], "repaymentDetails": [ { "effectiveDate": "AAAA", "schedules": [ { "repaymentType": "B", "description": "ddd", "paymentMethod": "AAA", "paymentFrequency": "dd", "paymentFrequencyDescription": "dddddd", "payments": [ { "startDate": "bb", "endDate": "EEEEEE", "numberOfPayments": "e", "calculatedPaymentAmount": "AAA" } ], "nextPaymentDate": "EE" } ] } ], "limit": [ { "limitKey": "DD", "limitReference": "EEEE", "limitSerial": "CCCCCCCCC" } ], "interest": [ { "rateName": "bbbb", "rateDescription": "", "interestConditions": [ { "effectiveDate": "BBB", "rateTierType": "CCCC", "tierDetails": [ { "fixedRate": "BBBBB", "floatingIndex": "D", "periodicDetails": [ { "periodicIndex": "bbbbb", "periodicType": "cc", "periodicRate": "CCCC", "periodicPeriod": "CCC", "periodicMethod": "", "initialResetDate": "AA", "periodicReset": "AAAAAAA", "nextResetDate": "ccccc" } ], "margins": [ { "marginType": "ccccccc", "marginOperand": "b", "marginRate": "c" } ], "tierAmount": "E", "tierPercent": "", "effectiveRate": "cccc", "linkedRateIndicator": "BBBBBBBB" } ] } ] } ], "settlementDetails": [ { "payinSettlement": [ { "payinPaymentTypes": [ { "payinPaymentType": "aaaaaaaaa", "description": "AAA" } ], "payinDetails": [ { "payInPoProduct": "eeeee", "payInAccount": "B", "payInBeneficiary": "ddd" } ] } ], "payoutSettlement": [ { "payoutDetails": [ { "payoutAccount": "aaaaaaa", "payoutBeneficiary": "eeee", "payOutPoProduct": "cccccccc" } ], "payOutPropertyClasses": [ { "propertyClassId": "DDDDDDDD", "propertyClassName": "CCC" } ], "payOutProperties": [ { "propertyId": "cc", "propertyName": "d" } ] } ], "defaultSettlementAccounts": [ { "defaultSettlementAccount": "" } ] } ], "officerDetails": [ { "primaryOfficer": "BBBBBBBBB", "otherOfficers": [ { "otherOfficer": "c", "otherOfficerRole": "" } ] } ], "productCategoryId": "dddd", "shortTitles": [ { "language": "CCCCCCC", "shortTitle": "BBBBBBB" } ], "coolingOffDate": "aaaaaaaaa", "renewalDate": "EEE" }
Setting Overdraft Limit
API
The overdraft limit is set or amended using the following API. The API uses tags to pass the secondary limit amount(the overdraft (OD) amount).
/v1.0.0/holdings/accounts/savingsAccounts/{savingsAccountId}/limits
Event
The following event is emanated after the API is executed.
accounts.updateLimit.limitUpdated
Event Payload
As before, this event carries the baseDetails, accountBaseDetails and feeDetails. It also carries the newly updated secondary limit amount figures.
limit |
Carries the secondary limit ( |
- Sample Code: Overdraft Limit Updated Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "accountsBaseDetails": [ { "overdraftStatus": "DDDDDDD", "dormancyStatus": "ccccccc", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "d", "currency": "dddddd", "multiCurrencyAccountBalances": [ { "currency": "CCCCCCCC", "balances": [ { "balanceName": "CCCC", "closingBalance": "BBBBB", "dateType": "", "debitTotalAmount": "b", "creditTotalAmount": "ddddddddd", "timeStamp": "EEEE" } ] } ] } ] } ], "baseDetails": [ { "contractReference": "ddddddddd", "systemReference": "DD", "companyReference": "A", "eventName": "EEEEEEEE", "baseEventIdentifier": "aaaaaaaaa", "effectiveDate": "", "bookingDate": "cccccc", "contractCurrency": "aaaaaa", "channel": "ddd", "branch": "eeeeeeee", "lineOfBusiness": "EEEEEEE", "activityDateTimeStamp": "EEEEE", "transactionReference": "b", "reversalIndicator": true, "originationReference": "BBBBBBBBB", "contractStatus": "EEEEE", "accountId": "ccccc", "overdue": "CCCCCC", "feeDetails": [ { "feeName": "bbbbbb", "feeAmount": "eeee", "feeCurrency": "bb", "adjustFeeAmount": "DDDDD", "adjustFeeReason": "B" } ], "balances": [ { "balanceName": "AA", "closingBalance": "DDD", "dateType": "CCCCCCCC", "debitTotalAmount": "dddd", "creditTotalAmount": "EEE", "timeStamp": "dddd" } ] } ], "limit": [ { "secondaryLimit": "eeeeeee", "secondaryLimitAmount": "" } ] }
Credit/Debit Account
API
Typically, the credit or debit is performed on AR through a GAI(Generic Accounting interface), which have their own APIs to access the underlying account and adjust the balances. The following APIs give direct access to the account.
/v1.0.0/holdings/accounts/savingsAccounts/{savingsAccountId}/credits
/v1.0.0/holdings/accounts/savingsAccounts/{savingsAccountId}/credits
Event
These are the events that are emanated when a credit or debit is made to the savings account.
accounts.credit.transactionExecuted
accounts.debit.transactionExecuted
Event Payload
Both events carry the same payload - they're differentiated through event types so that they can be consumed by the systems which are interested in them.
balances |
Carries the details of the balances after the credit/debit. Usually, either the |
context |
Carries information if the debit/credit happened within a specific context – for example, if the credit was performed with 100 rolled coins. These are typically used in pricing 0, if the fee is computed based on the number of rolled coins. |
- Sample Code: Credit/Debit Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "transactionCurrency": "dddddddd", "transactionAmount": "ee", "contractAmount": "ccccccccc", "baseDetails": [ { "contractReference": "EEEEEEEE", "systemReference": "", "companyReference": "DDDDDD", "eventName": "CCCC", "baseEventIdentifier": "BBBBB", "effectiveDate": "", "bookingDate": "b", "contractCurrency": "ddddddddd", "channel": "EEEE", "branch": "AAAAAA", "lineOfBusiness": "BBBBBBBB", "activityDateTimeStamp": "eeeeee", "transactionReference": "CCCCCCCC", "reversalIndicator": false, "originationReference": "e", "contractStatus": "AAAAAAAAA", "accountId": "", "overdue": "BBB", "feeDetails": [ { "feeName": "AAAA", "feeAmount": "aaaaaaaaa", "feeCurrency": "DDDDDDD", "adjustFeeAmount": "", "adjustFeeReason": "bbbbb" } ], "balances": [ { "balanceName": "bb", "closingBalance": "AAAAAAAAA", "dateType": "cccccccc", "debitTotalAmount": "A", "creditTotalAmount": "A", "timeStamp": "" } ] } ], "accountsBaseDetails": [ { "overdraftStatus": "DDDDDDDDD", "dormancyStatus": "E", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "EEEEEEEE", "currency": "aaaaaaaa", "multiCurrencyAccountBalances": [ { "currency": "DDD", "balances": [ { "balanceName": "C", "closingBalance": "CCC", "dateType": "eeeeee", "debitTotalAmount": "", "creditTotalAmount": "EEEEEE", "timeStamp": "DDDD" } ] } ] } ] } ], "context": [ { "contextName": "", "contextValue": "dddd" }, { "contextName": "A", "contextValue": "AAAAAA" } ] } }
Overdraft Ageing
The ageing of overdraft - which occurred with the debit in our lifecycle - is based on the overdraft settings in the accounts TBC. Chasers may also be sent to inform the customer. Because this happens automatically through settings, only the event is discussed here.
Event
accounts.overdraftLimit.limitOverdrawn
Event Payload
accountBaseDetails |
Carries the overdraft status, indicating the age of the overdraft. |
- Sample Code: Credit/Debit Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "baseDetails": [ { "contractReference": "DDDDDDD", "systemReference": "ccccccc", "companyReference": "eee", "eventName": "EEEEEEEE", "baseEventIdentifier": "", "effectiveDate": "DDDDDD", "bookingDate": "CCCC", "contractCurrency": "BBBBB", "channel": "", "branch": "b", "lineOfBusiness": "ddddddddd", "activityDateTimeStamp": "EEEE", "transactionReference": "AAAAAA", "reversalIndicator": true, "originationReference": "dddd", "contractStatus": "bbb", "accountId": "DDDDDDDD", "overdue": "e", "feeDetails": [ { "feeName": "EEEEEEEE", "feeAmount": "AAAAAAA", "feeCurrency": "dddddd", "adjustFeeAmount": "AAAA", "adjustFeeReason": "aaaaaaaaa" } ], "balances": [ { "balanceName": "BBBBBBBB", "closingBalance": "BBBBBB", "dateType": "DDDDDDDD", "debitTotalAmount": "bb", "creditTotalAmount": "AAAAAAAAA", "timeStamp": "cccccccc" }, ] } ], "accountsBaseDetails": [ { "overdraftStatus": "EE", "dormancyStatus": "aaaaaaa", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "aaaaaaa", "currency": "DDD", "multiCurrencyAccountBalances": [ { "currency": "CCC", "balances": [ { "balanceName": "bbbbb", "closingBalance": "", "dateType": "", "debitTotalAmount": "b", "creditTotalAmount": "CCC", "timeStamp": "AAAA" } ] } ] } ] } ] } }
Set Dormancy
API
Dormancy can be set through an API, if the officer wishes do it this way, or it can be done automatically by the system. This API actions the manual dormancy setting.
/v1.0.0/holdings/accounts/savingsAccounts/{savingsAccountId}/dormancyStatus/{status}Event
When the dormancy is set, the following event is emitted. (If the dormancy is reset, then accounts.resetDormancy.dormancyReset is emitted instead.)
accounts.set.dormancySetEvent Payload
accountBaseDetails |
Carries the latest dormancy status. The value of the dormancy status is a setting in TBC, and banks would have multiple statuses. |
- Sample Code: Set Dormancy Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "baseDetails": [ { "contractReference": "DDDDDDD", "systemReference": "ccccccc", "companyReference": "eee", "eventName": "EEEEEEEE", "baseEventIdentifier": "", "effectiveDate": "DDDDDD", "bookingDate": "CCCC", "contractCurrency": "BBBBB", "channel": "", "branch": "b", "lineOfBusiness": "ddddddddd", "activityDateTimeStamp": "EEEE", "transactionReference": "AAAAAA", "reversalIndicator": true, "originationReference": "dddd", "contractStatus": "bbb", "accountId": "DDDDDDDD", "overdue": "e", "feeDetails": [ { "feeName": "EEEEEEEE", "feeAmount": "AAAAAAA", "feeCurrency": "dddddd", "adjustFeeAmount": "AAAA", "adjustFeeReason": "aaaaaaaaa" } ], "balances": [ { "balanceName": "BBBBBBBB", "closingBalance": "BBBBBB", "dateType": "DDDDDDDD", "debitTotalAmount": "bb", "creditTotalAmount": "AAAAAAAAA", "timeStamp": "cccccccc" }, ] } ], "accountsBaseDetails": [ { "overdraftStatus": "EE", "dormancyStatus": "aaaaaaa", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "aaaaaaa", "currency": "DDD", "multiCurrencyAccountBalances": [ { "currency": "CCC", "balances": [ { "balanceName": "bbbbb", "closingBalance": "", "dateType": "", "debitTotalAmount": "b", "creditTotalAmount": "CCC", "timeStamp": "AAAA" } ] } ] } ] } ] } }
Close Account
API
An account could be manually closed, based on its dormancy, or at the request of the client.
/v1.0.0/holdings/accounts/savingsAccounts/{savingsAccountId}/accountClosures
Event
accounts.close.accountClosed
Event Payload
contractStatus |
Carries a status of 'Closed'. |
closureReason |
Indicates the reason the account was closed. |
- Sample Code: Close Account Event Payload
-
{ "specversion": "BBBBBBB", "type": "AAAAAAAAA", "subject": "DDDDDDDD", "source": "eeeee", "id": "bbbbbbb", "time": "BBBBB", "correlationid": "cccccc", "serviceid": "ee", "channelid": "cc", "organizationid": "bbbbbbbb", "tenantid": "cccccc", "businesskey": "DDDDDDDDD", "sequenceno": 1, "authorization": "ccccccccc", "customfilterid": "eee", "operationinstanceid": "ccc", "sequenceinstanceid": "e", "priority": 1, "data": { "baseDetails": [ { "contractReference": "DDDDDDD", "systemReference": "ccccccc", "companyReference": "eee", "eventName": "EEEEEEEE", "baseEventIdentifier": "", "effectiveDate": "DDDDDD", "bookingDate": "CCCC", "contractCurrency": "BBBBB", "channel": "", "branch": "b", "lineOfBusiness": "ddddddddd", "activityDateTimeStamp": "EEEE", "transactionReference": "AAAAAA", "reversalIndicator": true, "originationReference": "dddd", "contractStatus": "bbb", "accountId": "DDDDDDDD", "overdue": "e", "feeDetails": [ { "feeName": "EEEEEEEE", "feeAmount": "AAAAAAA", "feeCurrency": "dddddd", "adjustFeeAmount": "AAAA", "adjustFeeReason": "aaaaaaaaa" } ], "balances": [ { "balanceName": "BBBBBBBB", "closingBalance": "BBBBBB", "dateType": "DDDDDDDD", "debitTotalAmount": "bb", "creditTotalAmount": "AAAAAAAAA", "timeStamp": "cccccccc" } ] } ], "accountsBaseDetails": [ { "overdraftStatus": "EE", "dormancyStatus": "aaaaaaa", "multiCurrencyAccountIds": [ { "multiCurrencyAccountId": "aaaaaaa", "currency": "DDD", "multiCurrencyAccountBalances": [ { "currency": "CCC", "balances": [ { "balanceName": "bbbbb", "closingBalance": "", "dateType": "", "debitTotalAmount": "b", "creditTotalAmount": "CCC", "timeStamp": "AAAA" }, { "balanceName": "", "closingBalance": "CCCCCCCCC", "dateType": "DDDDDDDD", "debitTotalAmount": "aaaaaaa", "creditTotalAmount": "aaaaaaaa", "timeStamp": "" }, { "balanceName": "EEEEEEE", "closingBalance": "ddddddd", "dateType": "", "debitTotalAmount": "dddd", "creditTotalAmount": "A", "timeStamp": "AAAAAA" } ] } ] } ] } ], "closureReason": "cccccccc", "closureNotes": "eeeeeeee", "closureDate": "eee" } }
Other Lifecycle Scenarios
We've just run through a fairly straightforward Savings Account lifecycle. Other common events that could have happened to the account, during its lifecycle, include the following:
|
Reserve funds on an account. |
a. API: |
|
Post a withdrawal notice (on notice accounts). |
a. API: |
|
Record posting restrictions (such as blocking an account from a debit or credit, or both). |
a. API: |
|
Make multiple Alert messages available. For example, a rule could be created to send an alert if the account balance goes below a specific threshold, or a alert could be requested during a overdraw. Alert messages are different from plain business events as they can be both set rule based, and subscribed specifically by notification systems. |
a. Event: |
Accounting Events
Accounting events are emitted in addition to business events for a variety of banking products, including savings accounts, current accounts, and other kinds of bank account. For more information, see the Accounting Event Lifecycle Guide
